Skip to content

feat(page-builder): keep block rich text to basic formatting - #216

Merged
clbotdev merged 8 commits into
mainfrom
feat/page-builder-lean-rich-text
Nov 22, 2026
Merged

clbotdev merged 8 commits into
mainfrom
feat/page-builder-lean-rich-text

Conversation

@clbotdev

@clbotdev clbotdev commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Page blocks used the documentation text-editor profile, so their rich text offered and accepted images, tables, tabs, steps, callouts, cards, buttons, web previews and H5P. Pages already have Media, Embed and other blocks for those.

This adds one pageTextProfile in @frontlit/page-builder/schema and uses it everywhere page rich text is handled.

Allowed:

  • paragraphs, headings 2–4, bullet and numbered lists, quotes, code blocks, dividers and line breaks;
  • bold, italic, strikethrough, inline code and links.

Not allowed: H1 (the block title is the heading), tables, underline and highlight (no Markdown form), and all text-editor blocks.

Where Before After
Builder editor (RichTextField) documentation profile pageTextProfile; the / menu, Insert menu and text styles only list allowed items
Block widgets TextRenderer with the default profile PageText with pageTextProfile
Validating saves: builder, REST and MCP (canonicalizeLayout) docs validator validateContent(pageTextProfile)
Git page files (Markdown) docs parser and serializer parseMarkdown and serializeMarkdown with pageTextProfile
What agents read "Markdown (CommonMark + GFM)" PAGE_TEXT_FORMAT in page.v1.json and the MCP update_page description; the Pages-from-Git docs updated too

Agents are told only the allowed format. Anything else is refused on save with a located message, for example /layout/1/settings/text Unsupported node: tabs. or line 1: Images are not allowed here.

The public TextRenderer re-export from @frontlit/page-builder/components is unchanged, because apps/web uses it for documentation content.

Content saved before this change

Rich text already holding an image, docs block, H1, underline or highlight no longer validates. Before the fix, opening such a page returned 500, because the draft-status hash validates the draft. QA's "My Team" homepage has an image in its hero description.

toPageText cuts that content down to what the profile allows: it drops nodes and marks outside it and moves headings into 2–4.

  • Builder: when the builder loads a page, it cleans every rich-text setting, so the first autosave stores a valid layout. The images and blocks are dropped.
  • Renderer: PageText renders only what the profile allows, so a published revision with old content still renders.
  • Page status: an invalid draft is reported as published_with_changes instead of failing.

Writes from REST, MCP and Git stay strict.

Editor follow-ups from local testing

  • No toolbar in page rich-text fields. Formatting comes from the menu over selected text, the / menu and Markdown shortcuts. Six of the nine fields already hid it; Rich text, Content and Grid now do too.
  • Dark mode. tokens.css only had light colours, set directly on the editor, so links were dark on dark and the toolbar stayed white. Added a matching dark set under .dark.
  • Keyboard access to the selection menu.
    • Escape in the text closes it until the selection changes.
    • Alt+F10, or Ctrl/⌘+Shift+Space, moves focus into it. The second key exists because laptop F-rows and GPU overlays (NVIDIA Instant Replay) often take Alt+F10. Both keys also reach the table bar and block controls.
    • Inside, ←/→/Home/End move between buttons, and Escape returns to the text with the selection kept.
    • It is a toolbar labelled "Text formatting", and the mark buttons report on/off with aria-pressed.
    • Documented in the README keyboard table, the docs site and the package AGENTS.md.

Public site: font preload and CSS

  • Font preload never reached the HTML on any hosted site (sendlit.app, medialit.cloud, frontlit.app), and it was still broken on main.
    • The tenant layout called preload() from react-dom after the root layout's <head> had streamed, so the hint only went into the RSC payload (:HL[…]). The browser acted on it after the scripts ran.
    • The layout now renders <link rel="preload" as="font"> tags, which React hoists into <head>. Verified in a production build: the link is at byte ~1,300, before </head> at ~13,500.
  • Public pages loaded the editor's whole stylesheet. @frontlit/text-editor/styles.css is a complete Tailwind build including the toolbar, menus and block settings, and Tailwind also scanned editor-only files.
    • The site now imports prose.css only and skips the editor-only files.
    • Computed styles are identical for every element on the home page (287) and a docs page with every rich block (194).
CSS per page Raw Gzip
Live sites today (v0.0.1 build) 276.5 KB 43.0 KB
This branch, production build 262.6 KB 40.0 KB

Most of the remaining ~246 KB comes from page-builder styles, which #149 tracks.

Testing

  • Unit tests: page-builder (65, including new tests that Markdown and stored JSON with #, tables, images, <Callout>, <Tabs> and H1 are rejected and basic content round-trips) and API pages/MCP (75); tsc passes for page-builder, api and web.
  • Local browser smoke on the Privacy page's Rich text block:
    • the Insert menu shows only Code block and Divider;
    • the style menu shows Paragraph and H2–H4;
    • the / menu shows only the Text section;
    • a code block inserted with /code saves ("Draft saved") and renders in the canvas and on the published public page.
  • Local API: PATCH layouts with an image, tabs and an H1 each returned 400 with a message saying why. MCP update_page calls the same updatePage and canonicalizeLayout.
  • Every local stored page draft and published revision (24) still validates under the new profile.
  • Legacy content, tested locally: an image in a hero description and an image plus callout in the live revision.
    • The page opens and its first save stores the cleaned layout ("Draft saved"; status back to published).
    • The public site returns 200 with the text, without the image or callout.
  • QA deploy and smoke on qa-pr216-a367f8a:
    • the same builder menus as locally;
    • a code block saves and renders on the public /privacy page;
    • the API refuses an image, tabs and an H1;
    • MCP tools/list shows the new update_page description;
    • MCP update_page with a callout returns "Unsupported node: callout.".
  • QA again on the legacy-content fix.

Page blocks used the documentation profile, so their rich text took
images, tabs, steps, callouts and every other text-editor block. A page
text profile now drives the builder's editor, the renderer, validation
and Markdown page files, and the JSON Schema and MCP update_page
describe it, so agents see only what is allowed and saves refuse the rest.
…ofile

A draft holding an image or docs block made the page GET fail (the
draft-status hash validates) and would make the site renderer throw.
toPageText cuts such text down to the profile: the builder cleans every
rich-text setting on load, so its first save stores a valid layout, the
renderer shows only what the profile holds, and the status check treats
an invalid draft as changed instead of failing.
Every page rich-text field now hides the editor toolbar, as most already
did; formatting comes from the selection menu, the / menu and Markdown
shortcuts.
tokens.css set light-only colours on .tiptap-editor and the portaled menus,
overriding a dark host's tokens: links (var(--primary)) rendered dark on
dark and the toolbar stayed white. Add the matching dark set under .dark.
Escape in the text closes the menu until the selection changes (a
dismissed flag in the plugin's shouldShow, so refocusing doesn't reopen
it). Alt-F10 with text selected shows it at once and focuses it; it is a
labelled toolbar with arrow/Home/End movement, aria-pressed on mark
buttons, Escape back to the text and from the link field to its button.
Alt+F10 often never reaches the page: laptop F-rows default to hardware
keys and GPU overlays (NVIDIA Instant Replay) take it. Mod-Shift-Space
does the same: formatting menu, table bar or block controls. Documented
in the README keyboard table, the docs site and the package AGENTS.md.
Font preload never reached the HTML on any hosted site: the tenant layout
called react-dom preload() after the root layout's <head> had streamed,
so the hint only went into the RSC payload and the browser acted on it
after the scripts ran. Render the <link rel=preload> tags instead; React
hoists them into the head (verified in a production build).

Public pages loaded the editor's whole Tailwind build
(@frontlit/text-editor/styles.css: toolbar, menus, block settings) and
scanned editor-only files for utilities. Import prose.css only and skip
the editor-only files: 276.5 KB -> 262.6 KB raw (43.0 -> 40.0 KB gzip)
of CSS per page, with identical computed styles on the home and docs
pages (every element compared).
Theme link styles are made for navigation (no-underline, hover:underline),
so a link inside a sentence was marked only by font weight (WCAG 1.4.1)
and looked different from the editor, which underlines. The renderer now
always adds underline underline-offset-4 after the theme's classes.
@clbotdev
clbotdev merged commit f562d28 into main Nov 22, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants